home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / sharewar / FFE / GRAPH.SWG / 0041_DORE Raster Format.pas < prev    next >
Pascal/Delphi Source File  |  1997-05-11  |  12KB  |  279 lines
  1. This summary of the Dore file format was compiled by Steve Hollasch of
  2. Kubota Pacific and is included with permission.
  3.  
  4.  
  5.                         ==============================
  6.                            DORE' RASTER FILE FORMAT
  7.                         ==============================
  8.  
  9.  
  10.  
  11.     Dore' is an object oriented 3D graphics library that enables the user to
  12.     produce both dynamic image sequences and near-photographic quality
  13.     images.  Dore' is device independent and supports multiple output devices
  14.     and renderers.  It provides a rich set of graphics attributes, including
  15.     features such as 2D and 3D texture mapping and filtering.
  16.  
  17.     The Dore' raster file format was developed in order to store and retrieve
  18.     information for texture mapping, environment mapping, bump mapping, voxel
  19.     fields and so on.  It provides for the representation of two- and three-
  20.     dimensional rasters of a variety of different data types, including
  21.     color, transparency, and depth information.  This document describes the
  22.     file format used by Dore' for raster data.
  23.  
  24.  
  25. Raster File Data Interpretation
  26. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  27.  
  28.     A pixel (picture element) is the set of information associated with a
  29.     specific point in a two-dimensional raster image.  A voxel (volume
  30.     element) is the three-dimensional analog of a pixel, and is used when
  31.     referring to three-dimensional rasters.  In Dore', a pixel or voxel
  32.     consists of certain combinations of red, green, blue, alpha, and Z image
  33.     data.  This section describes the meaning of the values of these pixel
  34.     and voxel components.
  35.  
  36.     RGB Data:  RGB color information describes the color of each pixel/voxel,
  37.     and is represented by three 8-bit unsigned integer byte values.  Each
  38.     value represents the intensity of light for that color channel.  A value
  39.     of 0 means no light, and a value of 255 means full intensity light.
  40.  
  41.     Alpha Data:  Alpha information describes the transparency of the
  42.     pixel/voxel, and is represented as a single 8-bit unsigned integer byte
  43.     value.  A value of 0 means the pixel/voxel is opaque, and a value of 255
  44.     means it is completely transparent.  Alpha information is used in image
  45.     compositing.
  46.  
  47.     Z Data:  The Z information describes the relative distance of the
  48.     pixel/voxel from a point of reference, and is stored as a 32-bit unsigned
  49.     integer.  A value of 0 represents a distance as far away as possible, and
  50.     a value of 4,294,967,295 (or 2^32 - 1) represents a distance as close as
  51.     possible.  For example, if the image is a two-dimensional rendering of a
  52.     three-dimensional scene, then the Z data could be the distance of the
  53.     visible surface from the eye.
  54.  
  55.  
  56. Raster File Format
  57. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  58.  
  59.     Raster files are used to store Dore' image data in computer file systems
  60.     and to allow other programs to communicate image data to Dore'.  Dore'
  61.     raster files consist of an ASCII header section followed by a binary data
  62.     section.
  63.  
  64.     An example of a raster file (with the binary data shown only as an
  65.     annotation) is given below:
  66.  
  67.                  # brick texture raster - Dore' Rasterfile
  68.                          rastertype = image
  69.                          width = 128
  70.                          height = 128
  71.                          depth = 1
  72.                          pixel = r8g8b8z32
  73.                          wordbyteorder = big-endian
  74.                  <ff><ff>
  75.                          .
  76.                          .
  77.                     (binary data)
  78.                          .
  79.                          .
  80.                  <EOF>
  81.  
  82.     The sections below describe the formats of the header and binary data
  83.     sections of raster files in more detail.
  84.  
  85.  
  86. Raster File Header
  87. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  88.  
  89.     The ASCII header of a Dore' raster file consists of several attribute-
  90.     value pairs followed by an end-of-header marker.
  91.  
  92.     An attribute-value pair is an attribute name followed by an equal sign
  93.     (=), followed by a numeric value or an identifier name value.  Optional
  94.     white space characters (spaces, tabs, newlines/linefeeds, or carriage
  95.     returns) may precede or follow the = character.
  96.  
  97.     Attribute-value pairs must be separated by white space characters.  The
  98.     convention is to have one attribute-value pair per line.
  99.  
  100.     Unknown attribute-value pairs are ignored.  An attribute may have
  101.     multiple values, separated by commas, even though this feature is not
  102.     currently used by Dore'.
  103.  
  104.     The end-of-header marker is a formfeed character (ASCII character 0x0c)
  105.     followed by zero or more nonformfeed characters followed by a formfeed
  106.     character.  The double formfeed end-of-header marker allows the header
  107.     section to be expanded to fall at the end of a disk block boundary.  This
  108.     improves efficiency on some machines.
  109.  
  110.     Comments consist of the pound sign (#) and any number of characters to
  111.     the end of the line.
  112.  
  113.     The attributes rastertype, width, height, and pixel are mandatory.  The
  114.     rastertype attribute is required to be the first attribute in the
  115.     header.  The order of all attributes other than rastertype is not
  116.     restricted.  Attribute names and value strings are case sensitive.
  117.  
  118.     Mandatory and optional attributes are listed below with their permissible
  119.     values.
  120.  
  121.          rastertype
  122.              (mandatory; must be first attribute) A character string
  123.              indicating the type of raster.  Must have the value
  124.              "image" to indicate that this is a Dore' raster image
  125.              file.
  126.  
  127.          width
  128.              (mandatory) An unsigned integer value indicating the
  129.              width of the raster image in pixels (or voxels).
  130.  
  131.          height
  132.              (mandatory) An unsigned integer value indicating the
  133.              height of the raster image in pixels (or voxels).
  134.  
  135.         depth
  136.              (optional - defaults to 1) An unsigned integer value
  137.              indicating the depth of the raster image.  For 2-D
  138.              rasters, the picture elements are pixels and depth is
  139.              1.  For 3-D rasters, the picture elements are voxels and
  140.              depth is greater than 1.
  141.  
  142.         wordbyteorder
  143.             (optional - defaults to big-endian) A character string
  144.             indicating the byte order of large unsigned integer
  145.             binary numbers stored in the file (used for Z values).
  146.             It has one of two values:
  147.  
  148.             big-endian
  149.                 Meaning the machine represents words in the order of
  150.                 most significant byte to least significant byte.
  151.  
  152.             little-endian
  153.                 Meaning the machine represents words in the order of
  154.                 least significant byte to most significant byte.
  155.  
  156.         pixel
  157.             (mandatory) A character string indicating the content of
  158.             each pixel in the raster image.  It has one of the
  159.             following values:
  160.  
  161.             r8g8b8
  162.                  Indicates that each pixel in the image consists of
  163.                  three 8-bit values, representing the RGB color
  164.                  components of the pixel.
  165.  
  166.             r8g8b8a8
  167.                  Indicates that each pixel in the image consists of
  168.                  four 8-bit values, representing the RGB color
  169.                  components and the alpha component of the pixel.
  170.  
  171.             a8b8g8r8
  172.                  Indicates that each pixel in the image consists of
  173.                  four 8-bit values, the alpha component of the pixel,
  174.                  and the color components in BGR order.
  175.  
  176.             r8g8b8a8z32
  177.                 Indicates that each pixel in the image consists of
  178.                 four 8-bit values and one 32-bit value, representing
  179.                 the RGB color components, the alpha component, and
  180.                 the Z depth component of the pixel.
  181.  
  182.             r8g8b8z32
  183.                 Indicates that each pixel in the image consists of
  184.                 three 8-bit values and one 32-bit value, representing
  185.                 the RGB color components, and the Z depth component
  186.                 of the pixel.
  187.  
  188.             a8
  189.                 Indicates that each pixel in the image consists of
  190.                 one 8-bit value representing the alpha component of
  191.                 the pixel.
  192.  
  193.             z32
  194.                 Indicates that each pixel in the image consists of
  195.                 one 32-bit value representing the Z depth component
  196.                 of the pixel.
  197.  
  198.     The following example shows sample values for the minimal header
  199.     attributes acceptable.
  200.  
  201.           # mountain background raster - Dore' Rasterfile
  202.               rastertype = image
  203.               width = 1280
  204.               height = 1024
  205.               pixel = r8g8b8
  206.           <ff><ff>
  207.  
  208.  
  209. Raster File Binary Data
  210. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  211.  
  212.     Raster image binary data for Dore' has seven basic formats depending on
  213.     which of the r8g8b8, r8g8b8a8, a8b8g8r8, r8g8b8a8z32, r8g8b8z32, a8, or
  214.     z32 types were specified for the pixels or voxels in the raster.
  215.  
  216.     For file based images, the binary data is logically read from and written
  217.     to the files in a byte-by-byte fashion.  Since RGB and alpha information
  218.     is represented as byte values, their representation and order in the file
  219.     is the same for all machines.
  220.  
  221.     Z information, however, consists of an unsigned 32-bit integer.  While
  222.     the position of the 32-bit value is the same in the file for all
  223.     machines, the order of the bytes in the value is machine dependent.  If
  224.     the word byte order on the machine writing the file goes from the most
  225.     significant byte first down to the least significant byte, the order is
  226.     called `big-endian'.  The ordering may then be optionally indicated in
  227.     the file header with the "wordbyteorder = big-endian" attribute-value
  228.     pair.  If the word byte order on the machine writing the file goes from
  229.     the least significant byte first up to the most significant byte, the
  230.     order is called `little-endian'.  In that case, the ordering must be
  231.     indicated in the file header with the "wordbyteorder = little-endian"
  232.     attribute-value pair.
  233.  
  234.     Binary data in Dore' raster files are stored in pixel interleaved
  235.     fashion, meaning that the data is stored pixel by pixel (voxel by
  236.     voxel).  All the information related to a pixel (voxel) is stored
  237.     consecutively in the file.
  238.  
  239.     The order of pixels (voxels) in the binary data section is in width, then
  240.     height, and then depth order.  The data starts with the upper left hand
  241.     front corner of the image data and scans out in a left to right, top to
  242.     bottom, front to back order.  The index related to width varies the
  243.     fastest, the index related to height varies the second fastest, and the
  244.     index related to depth varies the slowest.
  245.  
  246.     The following shows the order of the data for a single pixel (voxel) for
  247.     each of the seven formats.  Each <..> denotes one byte.  For big-endian,
  248.     <Z1> is the most significant byte.  For little-endian, <Z1> is the least
  249.     significant byte.
  250.  
  251.         r8g8b8
  252.             <red><green><blue>
  253.  
  254.         r8g8b8a8
  255.             <red><green><blue><alpha>
  256.  
  257.         a8b8g8r8
  258.             <alpha><blue><green><red>
  259.  
  260.         r8g8b8a8z32
  261.             <red><green><blue><alpha><Z1><Z2><Z3><Z4>
  262.  
  263.         r8g8b8z32
  264.             <red><green><blue><Z1><Z2><Z3><Z4>
  265.  
  266.         a8
  267.             <alpha>
  268.  
  269.         z32
  270.             <Z1><Z2><Z3><Z4>
  271.  
  272.  
  273.  
  274.  
  275. ______________________________________________________________________________
  276. Steve Hollasch                                   Kubota Pacific Computer, Inc.
  277. hollasch@kpc.com                                 Santa Clara, California
  278.  
  279.